final audit of ADK docs#464
Merged
jacksonyzj merged 14 commits intoaj/adk-docs-updatefrom Apr 23, 2026
Merged
Conversation
Audited each ADK section against the agent-lack source repo and the skills repo. Fixed incorrect content, documented missing features, tightened prose, removed trailing nav Cards, and refreshed dev console screenshots. Corrections: - CLI reference: added --profile global flag, corrected --format availability, added subsections for adk search, adk mcp, adk telemetry, adk theme - HITL: switched integration deps to string shorthand (object form is deprecated), reworded dev-mode warning to match the real constraint - Skills: matched install command args to source (-a codex claude-code), added adk_init_project to the MCP tools table - Evals: fixed Eval import path (@botpress/runtime -> @botpress/adk) and evals directory (src/evals -> evals), documented event/ expectSilence turns and idleTimeout - Debugging: removed bogus 'adk logs "webhook"' content-filter example, added since= and limit= tokens - Scripts: updated flag pass-through example to use -- separator - Actions: fixed callAction curl (chat.botpress.cloud -> api.botpress.cloud, added Authorization header) - Triggers: removed incorrect client parameter from handler table Documented missing features: - Tables: computed columns, \$options regex modifier, keyColumn, waitComputed - Actions: cached prop - Knowledge: search() method, Directory source options, description role - Zai: summarize format/intermediateFactor/sliding, answer() response types, rate() multi-criteria, group() initialGroups/maxGroups Flow and structure: - Rewrote evals with cleaner ordering - Restructured knowledge page with dev console inlined after Create - Moved action-vs-tool comparison to the asTool subsection - Tightened intros on knowledge and actions pages - Inlined dev console mentions into Create sections across pages - Removed trailing next-page Cards from nearly every page Screenshots updated: actions, agent-steps, evals, knowledge, logs, tables, traces, triggers. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ctions Continues the audit pass. Fixed inaccuracies, documented missing features, tightened prose, inlined dev console mentions, and refreshed screenshots. Workflows: - Added state prop, workflow.fail, workflow.execute - Added step.progress, noted getOrCreate default statuses - Rewrote ambiguous step-name uniqueness paragraph - Updated request.workflow.provide examples to pass request.step - Inlined workflow dev console mention into Create section Conversations: - Fixed tools title casing (Define Tools -> Define tools) - Clarified customComponent vs custom message types - Added execute() signal? prop (AbortSignal cancellation) - Noted nudge.interval default and max-unlimited behavior - Replaced Chat page screenshot with agent-steps screenshots - Fixed webchat integration install note (no auto-prompt) - Replaced duplicated Traces blurb with link to debugging page Setup: - Fixed swapped default model claim in configuration - Fixed evals.idleTimeout unit (seconds -> milliseconds) - Title casing: Agent Configuration / Environment Setup -> sentence case - Removed evals row pointing at src/evals, updated to evals/ - Trimmed project structure table to core files only - Reworked integrations install vs configure framing - Enable/disable example now leads with string shorthand - Inlined secrets and config dev console mentions into existing sections Screenshots refreshed: workflows, environment selector, secrets, config variables, integrations hub, integration config. Removed trailing next-page Cards from every page in these sections. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit
vale
adk/testing/scripts.mdx|46 col 79| [Vale.Spelling] Did you really mean 'args'?
adk/testing/scripts.mdx|46 col 121| [Vale.Spelling] Did you really mean 'args'?
adk/zai/classify.mdx|20 col 26| [Vale.Spelling] Did you really mean 'boolean'?
| </Info> | ||
|
|
||
| HITL (Human-in-the-Loop) lets your agent hand off a conversation to a live human agent. This is powered by two dependencies working together: the **HITL integration** (provides the transport to a helpdesk or agent platform) and the **HITL plugin** (provides the actions your code calls). | ||
| HITL (Human-in-the-Loop) lets your agent hand off a conversation to a live human agent. It's powered by two dependencies working together: the **HITL integration** (the transport to a helpdesk or agent platform) and the **HITL plugin** (the actions your code calls). |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'helpdesk'?
| }) | ||
| ``` | ||
|
|
||
| ## Organize evals |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'evals'?
|
|
||
| ## Organize evals | ||
|
|
||
| Evals have two organizing fields that pair with CLI filters: `tags` and `type`. |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Evals'?
|
|
||
| Evals have two organizing fields that pair with CLI filters: `tags` and `type`. | ||
|
|
||
| **Tags** are free-form labels. Use them to group evals you want to run together (smoke tests, critical paths, slow suites): |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'evals'?
| adk evals --tag smoke # Run only evals tagged "smoke" | ||
| ``` | ||
|
|
||
| **Type** marks what the eval is for: |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'eval'?
| adk evals --type regression # Run only regression evals | ||
| ``` | ||
|
|
||
| ## Run evals |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'evals'?
Incorporates PR #461 (adrian-kahali): - Get Started restructure: welcome -> introduction, new top-level quickstart, updated docs.json sidebar - Configuration page: <Tip> blocks linking to related guides, expandable config snippet, cleaner prose - Environment setup: consolidated secrets + config explanations, better wording - Integrations: clearer intro, CLI section labelled - Conversations: <CodeGroup> for channel matching, <Tip> blocks for cross-references - AI execution: <Note> for LLMz reference, tighter phrasing - Tools: highlight annotations on code blocks Conflicts resolved in favor of keeping the audit fixes from this branch (correct default model order, ms units for idleTimeout, evals/ path, agent-steps screenshot, no trailing Cards, no standalone Dev console sections, "Botpress Cloud" wording, real CLI reference secrets table instead of placeholder link) while taking Adrian's <Tip>/<Note> block styling and structural improvements. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
jacksonyzj
changed the title
| - Chat with your agent | ||
| - Browse its components (actions, workflows, triggers) | ||
| - Manage data (tables, knowledge bases, files) | ||
| - Run evals |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'evals'?
| ## Arguments | ||
|
|
||
| Extra arguments after the script path are passed to your function: | ||
| Extra arguments after the script path are passed to your function. Positional args pass through directly; put flag-like args (anything starting with `-`) after a `--` separator so Commander doesn't try to parse them: |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'args'?
| ## Arguments | ||
|
|
||
| Extra arguments after the script path are passed to your function: | ||
| Extra arguments after the script path are passed to your function. Positional args pass through directly; put flag-like args (anything starting with `-`) after a `--` separator so Commander doesn't try to parse them: |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'args'?
| // true | ||
| ``` | ||
|
|
||
| Call `.result()` for the boolean plus the LLM's reasoning: |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'boolean'?
Introduction: - Tightened intro paragraph - Added Custom components to primitives table - Dropped src/ qualifier since evals live at the project root Quickstart: - Swapped em-dash for colon in the requirements list - Dropped filler sentence at the top of Test your agent - Removed the 'Chat in the terminal' section so readers land in the dev console - Normalized smart apostrophe Refreshed welcome and quickstart screenshots.
adkah
approved these changes
Apr 23, 2026
adkah
added a commit
that referenced
this pull request
Apr 27, 2026
* docs(adk-v2): scaffold get-started section with install page Add the Install page covering CLI prerequisites, install scripts for macOS/Linux/Windows, version pinning, custom install directory, self-upgrade, and the npm alternative. Empty placeholders for quickstart, welcome, and quickstart-with-coding-assistant land alongside to establish the v2 get-started structure. * docs(adk-v2): add quickstart page * docs(adk): replace intro/quickstart/project-structure with new Get started section Consolidates the ADK v2 install and quickstart drafts into a new Get started folder inside the existing ADK docs, and removes the standalone introduction, quickstart, and project-structure pages whose content is folded into the new pages (or covered by upcoming v2 concept pages). Drops the separate ADK v2 sidebar group. Updates docs.json, the ADK card on the home page, and the Zai overview link to point at the new paths so the broken-links check stays green. * docs(adk): simplify install page * docs(adk): fix vale warnings on quickstart * docs(adk): drop Botpress account prerequisite from install page * docs(adk): expand quickstart with project tree and adk dev breakdown * docs(adk): show step labels, package manager wizard, and workspace linking in quickstart * docs(adk): add control panel screenshots to quickstart * docs(adk): tighten quickstart to feel quick again * docs(adk): highlight hello-world in template wizard output * docs(adk): note that quickstart tree is an abbreviated view * docs(adk): add welcome and coding assistant quickstart pages * docs(adk): consolidate images into adk/assets * docs(adk): restructure welcome around start here, what you can build, resources * docs(adk): add hero image to welcome page * docs(adk): swap build with ai card for whats new linking to changelog * docs(adk): add quickstart next-step cards to install page * docs(adk): drop check and next steps from quickstart * docs(adk): rewrite coding assistant quickstart around skills * docs(adk): drop botpress cloud card from welcome resources * docs(adk): add debug and evals prompt examples to coding assistant quickstart * docs(adk): drop npm install path from install page * docs(adk): highlight instructions line and clarify edit hint * docs(adk): lead coding assistant quickstart with build with AI framing * docs(adk): match deploy section detail with main quickstart * docs(adk): restructure quickstarts with Steps and goal statement * docs(home): point adk card to welcome with get started cta * docs(adk): smooth out package manager and workspace linking prose * docs(adk): swap persistent state jargon for plain language * docs(adk): rename control panel to dev console, split run step into beats * docs(adk): show more files in quickstart tree, drop hidden files apology * docs(adk): replace notion prompt with coin flip and group examples in accordions * docs(adk): tighten coding assistant quickstart description and intro * docs(adk): replace coin flip with recipe prompt, frame accordions as starter samples * docs(adk): lead coding assistant quickstart with goal and introduce skills table * docs(adk): swap add a feature prompt to email collection into a table * docs(adk): drop timing estimate from coding assistant goal * docs(adk): explain skills vs slash commands in coding assistant quickstart * docs(adk): add adk login as first step in quickstart * docs(adk): show profile selection screen in adk login step * docs(adk): simplify adk login step to command plus one sentence * docs(adk): drop timing claim from quickstart opener * docs(adk): simplify welcome to hero plus quickstart and whats new * docs(adk): fold install into quickstart as step 1, drop install page * docs(adk): collapse welcome intro to a single tagline * docs(adk): swap quickstart intro for casual hello-world framing * docs(adk): tighten quickstart to 5 steps and drop project structure inline * docs(adk): switch install commands to accordion group by OS * chore: nudge mintlify preview * docs(adk): align next steps card with configuration page it links to * docs(adk): use folder icon and plain description for project structure card * docs(adk): reshape coding assistant quickstart into a drop-in 3-step flow * docs(adk): generalize coding assistant refs and point next steps forward * docs(adk): restructure sidebar and rewrite Get Started section Reorganize the ADK docs from a flat "Concepts" list into 11 topic-based groups matching the new documentation plan. Rewrite Welcome and Quickstart pages with verified, accurate content. Remove standalone Install page (folded into Quickstart) and Quickstart with coding assistant page. Add stub files for all new sections (setup, conversations, workflows, external, data, testing, zai utilities, ai-native, advanced). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(adk): write Setting up your agent section Add content for Agent Configuration (project structure, defineConfig walkthrough), Environment Setup (secrets, configuration values, dev/prod, preflight checks), and Integrations (dev console hub as primary, CLI as secondary, config stored on Botpress Cloud per bot). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(adk): write Handling conversations section Seven pages covering the full conversation lifecycle: - Set up conversations: channels, handler types, events, state - Run AI agents: execute() loop, instructions, knowledge, exits, hooks - Define Tools: standalone, inline, actions/workflows as tools, signals - Send messages: message types, typing, tags, Conversation.get() - Custom components: .bp.tsx, direct send, LLM-driven, build pipeline - Manage lifecycle: nudge, expiration, sessions, mermaid flow diagram - Manage states: bot/user/conversation scopes, User.get(), references, tags Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(adk): write Handling longform logic section Three pages covering workflows: - Create workflows: definition, starting (programmatic, scheduled, as tool), deduplication, instance methods, timeout, handler params - Use workflow steps: persistence, retries, sleep, listen, fail/abort, child workflows, parallel processing (map, forEach, batch) - Request and notify: step.request/provide, step.notify, workflow callbacks, summary table of mechanisms Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(adk): write Actions and triggers section Rename section from "Allowing interaction from outside" to "Actions and triggers". Rename "Build Actions" to "Create actions" for consistency. - Create actions: definition, calling from all primitives, .asTool(), integration actions, external API access via Runtime API - Set up triggers: event subscriptions, custom events, multiple events, calling actions from triggers Remove standalone scheduling page (already covered in Create workflows). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(adk): write Working with data section - Tables: schema definition, naming rules (verified against regex), CRUD operations, filtering operators, semantic search, aggregation, dev console - Knowledge bases: all data source types (sitemap, base URL, llms.txt, specific URLs, directory), using in conversations, refresh workflow, RAG Search view, dev console Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(adk): write Testing and debugging section - Write and run evals: file format, conversation turns, all assertion types (response, tools, state, tables, workflow, timing), llm_judge, setup/seeding, outcome assertions, CLI commands, dev console - Agent Steps: real-time debugging panel in Chat view - Debug with logs and traces: Traces view, Logs view, adk logs CLI - Run scripts: adk run, script exports, arguments, prod mode Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(adk): write LLM Utilities section - Introduction to Zai: adk.zai access, method overview table, model config - Extract structured data: basic/complex schemas, practical example - Generate text and summaries: text, rewrite, summarize, answer, patch - Classify, validate and filter: check, label, filter, sort, rate, group All 12 methods verified against latest Zai source. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(adk): write AI Native Development section Skills page covering all 6 ADK skills, slash commands, installation (packaged with adk init), and MCP server setup. Removed Agent (O) and Autonomous loops from sidebar (pre-beta). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(adk): write Advanced section, clean up orphaned files Add HITL page (from Linear guide): setup, plugin wiring, starting handoff, alternative providers, deploy warning. Remove orphaned files no longer in sidebar: - adk/concepts/ (9 files, replaced by new structure) - adk/runtime.mdx, adk/managing-integrations.mdx, adk/zai/reference.mdx - adk/advanced/frontend.mdx, autonomous-execution.mdx, tracked-state.mdx - adk/ai-native/agent-o.mdx, autonomous-loops.mdx Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(adk): add note distinguishing HITL from Botpress Desk Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(adk): rewrite CLI reference from source Complete rewrite of CLI reference verified against cli.ts. Grouped by category (project, integrations, configuration, chat/testing, workflows, debugging, knowledge, assets, AI assistants, account). Added missing commands: traces, workflows subcommands, assets, kb sync, models, profiles, self-upgrade, telemetry, theme, status, link. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(adk): expand ADK section by default in sidebar Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(adk): fix stale cards on Welcome page Remove Install and Quickstart with coding assistant cards that pointed to deleted pages. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs(adk): fix broken links and add placeholder images Fix two broken links pointing to deleted pages (frontend, autonomous execution). Add placeholder images for all dev console screenshots to unblock CI link checker. Placeholders should be replaced with actual screenshots. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * final audit of ADK docs (#464) * remove default expand * align get started section * audit configuration guide * quick fix to quickstart description * audit environment setup guide * audit integrations * audit conversations/setup * docs(adk): audit and polish ADK sections against source Audited each ADK section against the agent-lack source repo and the skills repo. Fixed incorrect content, documented missing features, tightened prose, removed trailing nav Cards, and refreshed dev console screenshots. Corrections: - CLI reference: added --profile global flag, corrected --format availability, added subsections for adk search, adk mcp, adk telemetry, adk theme - HITL: switched integration deps to string shorthand (object form is deprecated), reworded dev-mode warning to match the real constraint - Skills: matched install command args to source (-a codex claude-code), added adk_init_project to the MCP tools table - Evals: fixed Eval import path (@botpress/runtime -> @botpress/adk) and evals directory (src/evals -> evals), documented event/ expectSilence turns and idleTimeout - Debugging: removed bogus 'adk logs "webhook"' content-filter example, added since= and limit= tokens - Scripts: updated flag pass-through example to use -- separator - Actions: fixed callAction curl (chat.botpress.cloud -> api.botpress.cloud, added Authorization header) - Triggers: removed incorrect client parameter from handler table Documented missing features: - Tables: computed columns, \$options regex modifier, keyColumn, waitComputed - Actions: cached prop - Knowledge: search() method, Directory source options, description role - Zai: summarize format/intermediateFactor/sliding, answer() response types, rate() multi-criteria, group() initialGroups/maxGroups Flow and structure: - Rewrote evals with cleaner ordering - Restructured knowledge page with dev console inlined after Create - Moved action-vs-tool comparison to the asTool subsection - Tightened intros on knowledge and actions pages - Inlined dev console mentions into Create sections across pages - Removed trailing next-page Cards from nearly every page Screenshots updated: actions, agent-steps, evals, knowledge, logs, tables, traces, triggers. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * audit ai execution guide * revert next steps sections * audit tools page * docs(adk): audit Handling longform logic, conversations, and setup sections Continues the audit pass. Fixed inaccuracies, documented missing features, tightened prose, inlined dev console mentions, and refreshed screenshots. Workflows: - Added state prop, workflow.fail, workflow.execute - Added step.progress, noted getOrCreate default statuses - Rewrote ambiguous step-name uniqueness paragraph - Updated request.workflow.provide examples to pass request.step - Inlined workflow dev console mention into Create section Conversations: - Fixed tools title casing (Define Tools -> Define tools) - Clarified customComponent vs custom message types - Added execute() signal? prop (AbortSignal cancellation) - Noted nudge.interval default and max-unlimited behavior - Replaced Chat page screenshot with agent-steps screenshots - Fixed webchat integration install note (no auto-prompt) - Replaced duplicated Traces blurb with link to debugging page Setup: - Fixed swapped default model claim in configuration - Fixed evals.idleTimeout unit (seconds -> milliseconds) - Title casing: Agent Configuration / Environment Setup -> sentence case - Removed evals row pointing at src/evals, updated to evals/ - Trimmed project structure table to core files only - Reworked integrations install vs configure framing - Enable/disable example now leads with string shorthand - Inlined secrets and config dev console mentions into existing sections Screenshots refreshed: workflows, environment selector, secrets, config variables, integrations hub, integration config. Removed trailing next-page Cards from every page in these sections. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(adk): audit introduction and quickstart pages Introduction: - Tightened intro paragraph - Added Custom components to primitives table - Dropped src/ qualifier since evals live at the project root Quickstart: - Swapped em-dash for colon in the requirements list - Dropped filler sentence at the top of Test your agent - Removed the 'Chat in the terminal' section so readers land in the dev console - Normalized smart apostrophe Refreshed welcome and quickstart screenshots. --------- Co-authored-by: Adrian Kahali <adrian.kahali@hotmail.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * adk docs update audit (#461) * remove default expand * align get started section * audit configuration guide * quick fix to quickstart description * audit environment setup guide * audit integrations * audit conversations/setup * audit ai execution guide * revert next steps sections * audit tools page * audit custom components * audit messages * audit lifecycle and state * audit steps * audit request/notify * audit actions * fix actions description * audit triggers * audit tables * fix * fix vale * fix vale again * add redirects * fix links * audit knowledge * fix kb description * fix * docs(adk): fix accuracy issues from PR audit - configuration: move evals/ out of src/ in the project tree (evals live at the agent root, not under src/) - environment: remove duplicate standalone Dev console subsection under Configuration (image is already inlined above) - tools: drop src/tools/ from the lead-in since tools can live anywhere under src/ - tables: fix "Must with a letter" typo -> "Must start with a letter" * docs(adk): fix accuracy issues surfaced by end-to-end testing - evals: Eval import back to @botpress/runtime (it's exported from runtime/library.ts, not @botpress/adk; matches packages/lack/evals/*) - workflows: rename hyphenated workflow names to camelCase across create/steps/request-notify/evals/actions/knowledge/extract examples (generator emits unquoted keys in .adk/workflow-types.d.ts, so hyphenated names produce invalid TypeScript) - tables: drop `createdAt` from the OrderTable example (it's a reserved column per runtime/primitives/table.ts:320) - integrations: reconcile the Enable/Disable section so it no longer contradicts the CLI section about newly-added integrations being disabled by default --------- Co-authored-by: Jackson Yu <jackson.yu@botpress.com> --------- Co-authored-by: Jackson Yu <jackson.yu@botpress.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Adrian Kahali <adrian.kahali@hotmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Audited each ADK section against the latest source, fixed inaccuracies, and documented features that had shipped but weren't in the docs. Updated tone and flow to better match the docs style, and refreshed the dev console screenshots across pages.